=begin pod

=TITLE Reading the docs

=SUBTITLE p6doc - the Perl 6 pod reader

=head1 X<INTRODUCTION|p6doc>

Program C<p6doc> is a command-line-interface (CLI) program that reads
Perl 6 pod from B<installed> modules' source code, in contrast to
running C<perl6 --doc=MODULE programfile> which reads Perl 6 pod from
the named source file.

Note that C<p6doc> may not be installed automatically depending upon
how you installed Rakudo Perl 6.  To install it use C<zef>:

=for code :lang<usage>
 zef install p6doc

=head1 SYNOPSIS

=for code :lang<usage>
 p6doc [switches] [arguments]

=head1 DESCRIPTION

With no switches or arguments, C<p6doc> lists its help to C<$*OUT> (C<stdout>):

=begin code :skip-test
You want to maintain the index?
To build an index for 'p6doc -f'
          p6doc build

To list the index keys
          p6doc list

To display module name(s) containing key
          p6doc lookup

To show where the index file lives
          p6doc path-to-index

What documentation do you want to read?
Examples: p6doc Str
          p6doc Str.split
          p6doc faq
          p6doc path/to/file

You can list some top level documents:
          p6doc -l

You can also look up specific method/routine/sub definitions:
          p6doc -f hyper
          p6doc -f Array.push

You can bypass the pager and print straight to stdout:
          p6doc -n Str
=end code

The text output can be captured and converted to other forms if desired.

=head1 LIMITATIONS

Currently C<p6doc> can only extract embedded Perl 6 pod from installed
module source files (as listed in a distribution's C<META6.json>
file).  It is planned to add a feature for C<p6doc> (in conjunction
with C<META6.json> changes) to extract B<all> Perl 6 pod in files
included with the installed distribution.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
